.Dd $Mdocdate: February 16 2015 $
.Dt BIO_S_FD 3
.Os
.Sh NAME
.Nm BIO_s_fd ,
.Nm BIO_set_fd ,
.Nm BIO_get_fd ,
.Nm BIO_new_fd
.Nd file descriptor BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft BIO_METHOD *
.Fo BIO_s_fd
.Fa "void"
.Fc
.Fd #define BIO_set_fd(b,fd,c)	BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
.Fd #define BIO_get_fd(b,c)		BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
.Ft BIO *
.Fo BIO_new_fd
.Fa "int fd"
.Fa "int close_flag"
.Fc
.Sh DESCRIPTION
.Fn BIO_s_fd
returns the file descriptor BIO method.
This is a wrapper around the platform's file descriptor routines such as
.Xr read 2
and
.Xr write 2 .
.Pp
.Xr BIO_read 3
and
.Xr BIO_write 3
read or write the underlying descriptor.
.Xr BIO_puts 3
is supported but
.Xr BIO_gets 3
is not.
.Pp
If the close flag is set,
.Xr close 2
is called on the underlying file descriptor when the BIO is freed.
.Pp
.Xr BIO_reset 3
attempts to set the file pointer to the start of the file using
.Fn lseek fd 0 0 .
.Pp
.Xr BIO_seek 3
sets the file pointer to position
.Fa ofs
from start of file using
.Fn lseek fd ofs 0 .
.Pp
.Xr BIO_tell 3
returns the current file position by calling
.Fn lseek fd 0 1 .
.Pp
.Fn BIO_set_fd
sets the file descriptor of BIO
.Fa b
to
.Fa fd
and the close flag to
.Fa c .
.Pp
.Fn BIO_get_fd
places the file descriptor in
.Fa c
if it is not
.Dv NULL ,
it also returns the file descriptor.
If
.Fa c
is not
.Dv NULL ,
it should be of type
.Vt "int *" .
.Pp
.Fn BIO_new_fd
returns a file descriptor BIO using
.Fa fd
and
.Fa close_flag .
.Sh NOTES
The behaviour of
.Xr BIO_read 3
and
.Xr BIO_write 3
depends on the behavior of the platform's
.Xr read 2
and
.Xr write 2
calls on the descriptor.
If the underlying file descriptor is in a non blocking mode,
then the BIO will behave in the manner described in the
.Xr BIO_read 3
and
.Xr BIO_should_retry 3
manual pages.
.Pp
File descriptor BIOs should not be used for socket I/O.
Use socket BIOs instead.
.Sh RETURN VALUES
.Fn BIO_s_fd
returns the file descriptor BIO method.
.Pp
.Xr BIO_reset 3
returns zero for success and -1 if an error occurred.
.Xr BIO_seek 3
and
.Xr BIO_tell 3
return the current file position or -1 if an error occurred.
These values reflect the underlying
.Xr lseek 2
behaviour.
.Pp
.Fn BIO_set_fd
always returns 1.
.Pp
.Fn BIO_get_fd
returns the file descriptor or -1 if the BIO has not been initialized.
.Pp
.Fn BIO_new_fd
returns the newly allocated BIO or
.Dv NULL
if an error occurred.
.Sh EXAMPLE
This is a file descriptor BIO version of "Hello World":
.Bd -literal -offset indent
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\en");
BIO_free(out);
.Ed
.Sh SEE ALSO
.Xr BIO_read 3 ,
.Xr BIO_seek 3
